/*
 * Copyright 2002-2007 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package nl.jteam.jsa.core;

/**
 * A manager that enables access to the underlying search engine. Using this manager it is possible to manipulate the
 * search engine index (add/update/delete documents) and query it.
 *
 * @author Uri Boness
 */
public interface DocumentManager {

    /**
     * Adds the given document to the search engine corpus.
     *
     * @param document The document to be added.
     */
    void add(Document document);

    /**
     * Adds the given document to the search engine corpus.
     *
     * @param documents The documents to be added.
     */
    void add(Document[] documents);

    /**
     * Merges the given document with the search engine corpus. The merge is based on the document id
     * (see {@link Document#getId()}) - if the corpus already contains a document with the given id, then this document
     * is updated with the data/info of the given one, Otherwise the given document will be added to the corpus.
     *
     * @param document The document to be merged.
     * @return The merged document.
     */
    Document merge(Document document);

    /**
     * Deletes the document associated with the given type and id from the search engine corpus. Does nothing if no such document is
     * found.
     *
     * @param type The type of the document be delete.
     * @param id The id of the document to be deleted.
     */
    void deleteById(String type, String id);

    /**
     * Deletes all documents of the given type.
     *
     * @param type The type of the documents that need to be deleted.
     */
    void deleteByType(String type);

    /**
     * Deletes all documents in the corpus that match the given free text query and field filters.
     *
     * @param query The search query that will determine what documents should be deleted.
     */
    void deleteByQuery(SearchQuery query);

    /**
     * Searches the search engine corpus for documents that match the given free text query.
     *
     * @param freeTextQuery The free text query to match the documents.
     * @return The search result.
     */
    SearchResult search(String freeTextQuery);

    /**
     * Searches the search engine corpus for documents that match the given search query.
     *
     * @param query The search query to match the documents.
     * @return The search result.
     */
    SearchResult search(SearchQuery query);

    /**
     * Searches the search engine corpus for documents that match the given search query. Returns the search results with
     * the facets as defined by the search engine.
     *
     * @param query The search query to match the documents.
     * @return The faceted search result.
     */
    FacetedSearchResult search(FacetSearchQuery query);

    /**
     * Returns a trasaction that can be used to combine any of the document manager operations in an atomic unit of work.
     *
     * @return A trasaction that can be used to combine any of the document manager operations in an atomic unit of work.
     */
    DocumentTransaction getTransaction();

    /**
     * Closes this document manager. Calling this method should free all allocated resources the document manager is bound
     * with while active/open.
     */
    void close();

    /**
     * Clears the internal state of this docuemnt manager. NOTE as opposed to {@link #close()}, the document manager does
     * not have to close opened resources.
     */
    void clear();

}
